SST ShlWAPI PathAddExtension Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI PathAddExtension Function
Appends the specified file extension/suffix (or .exe) to the last name in a path string.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function PathAddExtension(pszPath : LPSTR; pszExt : LPCSTR) : BOOL;
	function PathAddExtension(pszPath : LPSTR; pszExt : LPCSTR) : BOOL; function PathAddExtension(pszPath : LPWSTR; pszExt : LPCWSTR) : BOOL;

Parameters
pszPath [in/out]	A pointer to a NULL terminated buffer, that on input contains the path and file/folder name to which the file suffix/extension should be added. If the function adds a file extension to the path, it is appended to the string in this buffer. The buffer should therefore be large enough to hold both the input string and the specified file extension (or .exe), including the period that separates both, and a terminating NULL character.
pszExt [in]	Pointer to a NULL terminated string that is the suffix/extension to append to the input string. This parameter can be NIL to induce the function to append ".exe" (without the quotation marks) as the extension.

Parameters

pszPath [in/out]

A pointer to a NULL terminated buffer, that on input contains the path and file/folder name to which the file suffix/extension should be added. If the function adds a file extension to the path, it is appended to the string in this buffer. The buffer should therefore be large enough to hold both the input string and the specified file extension (or .exe), including the period that separates both, and a terminating NULL character.

pszExt [in]

Pointer to a NULL terminated string that is the suffix/extension to append to the input string. This parameter can be NIL to induce the function to append ".exe" (without the quotation marks) as the extension.

Return Values
If the function added an extension to the string in the buffer, it returns TRUE, FALSE otherwise.

Remarks
The function does not verify the existence of any of the path's constituents.

Example
PROCEDURE TForm4.TestShlWAPIPathAddExtension(Sender : TObject); VAR pathstrbuf : ARRAY[0.. MAX_PATH] OF CHAR; VAR extension : STRING; VAR apiretval : BOOL; VAR newinfoline : STRING; BEGIN FillChar(pathstrbuf, Length(pathstrbuf), #0); extension := ''; apiretval := FALSE; newinfoline := ''; pathstrbuf := 'C:\Hello\World'; extension := '.txt'; newinfoline := pathstrbuf; newinfoline := 'PathAddExtension called with ' + newinfoline + ' and ' + extension; Memo1.Lines.Add(newinfoline); apiretval := PathAddExtension(pathstrbuf, PChar(extension)); IF apiretval THEN newinfoline := 'TRUE ' + pathstrbuf ELSE newinfoline := 'FALSE' + pathstrbuf; Memo1.Lines.Add(newinfoline); apiretval := FALSE; pathstrbuf := 'C:\Hello\World\'; extension := '.txt'; newinfoline := pathstrbuf; newinfoline := 'PathAddExtension called with ' + newinfoline + ' and ' + extension; Memo1.Lines.Add(newinfoline); apiretval := PathAddExtension(pathstrbuf, PChar(extension)); newinfoline := pathstrbuf; IF apiretval THEN newinfoline := 'TRUE ' + pathstrbuf ELSE newinfoline := 'FALSE' + pathstrbuf; Memo1.Lines.Add(newinfoline); apiretval := FALSE; pathstrbuf := 'C:\Hello\World\DummyName.csv'; extension := '.txt'; newinfoline := pathstrbuf; newinfoline := 'PathAddExtension called with ' + newinfoline + ' and ' + extension; Memo1.Lines.Add(newinfoline); apiretval := PathAddExtension(pathstrbuf, PChar(extension)); newinfoline := pathstrbuf; IF apiretval THEN newinfoline := 'TRUE ' + pathstrbuf ELSE newinfoline := 'FALSE' + pathstrbuf; Memo1.Lines.Add(newinfoline); apiretval := FALSE; pathstrbuf := 'C:\Hello\World\DummyName'; extension := ''; newinfoline := pathstrbuf; newinfoline := 'PathAddExtension called with ' + newinfoline + ' and an empty string'; Memo1.Lines.Add(newinfoline); apiretval := PathAddExtension(pathstrbuf, PChar(extension)); newinfoline := pathstrbuf; IF apiretval THEN newinfoline := 'TRUE ' + pathstrbuf ELSE newinfoline := 'FALSE' + pathstrbuf; Memo1.Lines.Add(newinfoline); apiretval := FALSE; pathstrbuf := 'C:\Hello\World\DummyName'; extension := ''; newinfoline := pathstrbuf; newinfoline := 'PathAddExtension called with ' + newinfoline + ' and NIL'; Memo1.Lines.Add(newinfoline); apiretval := PathAddExtension(pathstrbuf, NIL); newinfoline := pathstrbuf; IF apiretval THEN newinfoline := 'TRUE ' + pathstrbuf ELSE newinfoline := 'FALSE' + pathstrbuf; Memo1.Lines.Add(newinfoline); apiretval := FALSE; Memo1.Lines.Add(''); END;
The above example will produce the following output:
PathAddExtension called with C:\Hello\World and .txt TRUE C:\Hello\World.txt PathAddExtension called with C:\Hello\World\ and .txt TRUE C:\Hello\World\.txt PathAddExtension called with C:\Hello\World\DummyName.csv and .txt FALSEC:\Hello\World\DummyName.csv PathAddExtension called with C:\Hello\World\DummyName and an empty string TRUE C:\Hello\World\DummyName PathAddExtension called with C:\Hello\World\DummyName and NIL TRUE C:\Hello\World\DummyName.exe

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (PathAddExtension and PathAddExtensionA) and Unicode (PathAddExtensionW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	4.71
Min. ShlWAPI.dll version based on SST research:	4.71
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.:	Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later